home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / AMICUS / AMICUS18.ADF / Progs / StarProbe / ReadMe.DOC < prev    next >
Text File  |  1989-01-27  |  12KB  |  283 lines
  1. /*****************************************************************************
  2.  *                                                                           *
  3.  *                      S  T  A  R  P  R  O  B  E                            *
  4.  *                                                                           *
  5.  *               Copyright (c) 1987  by  Michael F. Purcell                  *
  6.  *                                                                           *
  7.  *                                                                           *
  8.  *  The author grants permission for the non-commercial distribution of this *
  9.  *  software, provided that this and other identifying information remains   *
  10.  *  intact.                                                                  *
  11.  *                                                                           *
  12.  *  .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    *
  13.  *                                                                           *
  14.  *  This software is provided "as-is" and carries with it no explicit or     *
  15.  *  implicit promise of support by the author.  Nor will the author be held  *
  16.  *  liable for any damages, real or imagined, which may result from the use  *
  17.  *  or abuse of this software.                                               *
  18.  *                                                                           *
  19.  *  .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .    *
  20.  *                                                                           *
  21.  *                                                                           *
  22.  *  This program calculates a mathematical model of a star's interior.       *
  23.  *                                                                           *
  24.  *  The author may be contacted via:                                         *
  25.  *                                                                           *
  26.  *     - Star Net:    as 'Mike Purcell'   (1-612-681-9520)                   *
  27.  *                                                                           *
  28.  *     - People/Link: as 'ASTRO*NUT'                                         *
  29.  *                                                                           *
  30.  *     - CompuServe:  as '73647,1102'                                        *
  31.  *                                                                           *
  32.  *****************************************************************************/
  33.  
  34.  Documentation Outline
  35.  
  36.     I. A Request from the Author
  37.    II. Program Background
  38.   III. Arc file descriptions
  39.    IV. Bibliography
  40.     V. Program Limitations
  41.    VI. Amiga vs. IBM-PC compile, link, & execute
  42.   VII. Input Parameter File
  43.  VIII. Program Structure & Flow
  44.    IX. Program Output: the Report
  45.     X. Program Output: the Data file
  46.    XI. Graphical Display in AmigaBasic
  47.   XII. Acknowledgements
  48.  
  49.  
  50.     I. A request from the Author
  51.  
  52.     I would appreciate feedback from users of this program. Please
  53.     inform me of errors found, modifications made, or resources I can use
  54.     to improve the algorithm. I would be especially grateful for
  55.     references to or examples of simple dynamic models.
  56.  
  57.  
  58.    II. Background
  59.  
  60.     This program grew out of my attempts (as an amateur astronomer) to
  61.     better understand stellar structure & evolution.  As such it is a
  62.     highly simplified model when compared with professional models running
  63.     on scientific supercomputers.  It really does nothing more than
  64.     recreate the kind of computations done BY HAND in the '40s & '50s
  65.     by people such as Chandrasekhar, Schwarzschild, and others.
  66.  
  67.     It is certainly not complete (see the section on Limitations),
  68.     but it does produce a reasonable model for our sun.  The algorithm
  69.     used is called the 'integration method'.  Its main drawback is that
  70.     it is not good for stars undergoing rapid change (post-main sequence).
  71.     This is not yet a problem because the program only performs a static
  72.     analysis.
  73.  
  74.     I attempted to keep the program structure as clean and modular as
  75.     possible. This was to facilitate changes.  No real code optimization
  76.         has been attempted.  A single complete integration takes approximately
  77.     1 minute on the Amiga, and somewhat longer on the IBM-PC.  The program
  78.     speed is dependent on the C compiler double-precision floating-point
  79.     software, and on the number of mass points being evaluated.
  80.  
  81.  
  82.   III. Arc file descriptions
  83.  
  84.         File        Description
  85.     ----        -----------
  86.  
  87.     astro.h        Astronomical constants
  88.     filter.c        A simple source filter for IBM-AMIGA movement cleanup
  89.     input.c        General input functions
  90.     msdos.chg    Source changes when moved from the Amiga to the IBM-PC
  91.     sp              A 'make' file for IBM
  92.     spdata1        A sample output data file to be used by spdraw.bas
  93.     spint.h        Global integer data
  94.     spflt.h        Global double precision floating point data
  95.     spmac.h        Global macros
  96.     spref.h        Invokes spint.h & spflt.h as 'extern'
  97.     spmain.c    Program outer block, owns global data
  98.     spinit.c    Initialization functions
  99.     speval.c    Physics/calculus evaluations & driver
  100.     spfit.c        Fitting point routines
  101.     sprpt.c        Output functions for reports & data
  102.     spdraw.bas    AmigaBasic program to plot the output data
  103.         link.amg        Linker input for the Amiga
  104.         link.ibm        Linker input for the IBM-PC
  105.         probe.amg       Executable program for the Amiga
  106.         spparm.dbg    Debugging input parameter file
  107.         spparm.in       Default input parameter file
  108.         spparm.doc      Parameter file documentation
  109.  
  110.  
  111.  
  112.    IV. Bibliography
  113.  
  114.     Most of the physics functions refer to one or more sources.
  115.     The sources are as follows:
  116.  
  117.     Bowers & Deeming, "Astrophysics I: Stars", Jones & Bartlett, 1984
  118.     (an excellent intermediate-level reference).
  119.  
  120.     Clayton, "Principles of Stellar Evolution and Nucleosynthesis",
  121.     McGraw-Hill, 1968.
  122.  
  123.     Motz, "Astrophysics & Stellar Structure", Ginn, 1970.
  124.  
  125.     Aller & McLaughlin (eds.), "Stellar Strucure", Univ. of Chicago Press,
  126.     1965.    
  127.  
  128.  
  129.     V. Program Limitations
  130.  
  131.     StarProbe performs a static analysis of the interior of an initial
  132.         main sequence star.  A dynamic analysis (of changes over time) would
  133.     require the tracking of entropy and composition, a complication
  134.     that I am not yet ready to attempt.  Using an 'initial' star permits
  135.     the assumption that the composition is the same throughout the star.
  136.     
  137.     The model is very sensitive to the initial parameters (central temp,
  138.     central pressure, surface luminosity, surface radius).  Currently,
  139.     if the mass parameter is set to 1.0 (the Sun) it uses known values.
  140.     This will result in a fairly accurate model.  The parameters resulting
  141.     from other initial mass values are not yet very good.
  142.  
  143.     Note that the differential equations which describe pressure, 
  144.     temperature, luminosity, and radius are all functions of the current
  145.     mass fraction (at the center m=0, at the surface m=M).  The mass
  146.     gradient defined in the parameter file directly affects the accuracy
  147.     and performance of the program.
  148.  
  149.     One problem area, which I have not yet resolved, is the function that
  150.     calculates opacity.  If the mass fraction at the fitting point is 0.5, then
  151.     the opacity values calculated between 0.3 and 0.5 of the mass are
  152.     incorrect.  Setting the fitting point to 0.3 hides most of this
  153.     problem.  It is possible that the reference I used for the opacity
  154.     function had a typo in the equations.  Replacing the approximation
  155.     formulae with published opacity tables is probably the best solution.
  156.  
  157.    VI. Amiga vs. IBM-PC compile, link, & execute
  158.  
  159.     I have made every effort to keep this program fully compatible with
  160.     the IBM-PC.  It was developed on an Amiga using Lattice C version 3.10.
  161.     It has been successfully downloaded to an IBM-PC, un-Arc'd, compiled,
  162.     linked, and executed.  The file names have been kept compatible with
  163.     MS-DOS, and no AmigaDos library facilities are used.
  164.  
  165.     Actually, this will run anywhere a "standard" C compiler is available.
  166.     The filter program is included to assist in cleaning up the source
  167.     for other (MacIntosh, Atari, UNIX, ...) environments.
  168.  
  169.     The program was broken into functional pieces for ease of development.
  170.     There is no reason why they can't be combined if that suits the user.
  171.  
  172.     Contrary to the first paragraph, the program to display the data is
  173.     written in AmigaBasic.  Nevertheless, because this Basic was developed by
  174.     MicroSoft, IBM-PC users should not have serious difficulty converting
  175.     it.
  176.  
  177.     To execute the program, simply 'run' it without parameters.  Everything
  178.     it needs is in "spparm.in".  
  179.  
  180.   VII. Input Parameter File
  181.  
  182.     The parameter file (described fully in spparm.doc) provides the
  183.     following information to the program:
  184.  
  185.       - Mass of the star
  186.       - Debug options
  187.       - Maximum integrations (when to give up)
  188.       - Composition
  189.       - Mass fraction at the fitting point
  190.       - The mass gradient values over which to integrate (total=1.0).
  191.  
  192.  
  193.  VIII. Program Structure & Flow
  194.  
  195.     The overall flow is fairly simple. The outer block (main) calls
  196.     Initialize to read the parameter file and set up the integration.
  197.     The Evaluator is called to perform the integration(s) and Shutdown
  198.     cleans up.
  199.  
  200.     After setting up the fitting point, the evaluation driver will:
  201.  
  202.       1. Integrate from the surface to the fitting point
  203.       2. Integrate from the center to the fitting point
  204.       3. Write the results to a new output file
  205.       4. Evaluate the fitting point and determine new initial values
  206.  
  207.     until the discrepancies at the fitting point are 'small' enough.
  208.  
  209.     My experience so far is that the driver will reach the maximum
  210.     integration value before it likes the fitting point values.  It
  211.     seems that the 2nd or 3rd integration usually produces the smoothest
  212.     data curves.  After that, the values get worse, not better.  I am not
  213.     sure if the fitting procedure has an error, or if 'small enough' is
  214.     too small. 
  215.  
  216.     All functions are assigned a number.  This number is used when
  217.     turning on the trace facilities or when an error is detected.
  218.     The best way to follow the progress of the integration is to
  219.     turn on tracing for the evaluation driver and the main integrator.
  220.     Setting this up is described in 'spparm.doc'.  Beware: even a limited
  221.     trace request will generate a large amount of output for each
  222.     integration.
  223.  
  224.     The program uses an 'assertion' macro to detect unreasonable or
  225.     impossible values.  When a bad value is detected, the bad value
  226.     and related parameters, along with the procedure number, are
  227.     displayed.
  228.  
  229.  
  230.    IX. Program Output: the Report
  231.  
  232.     A summary of the results is writtem to 'sprpt.out' after each 
  233.     integration.  This report is rather crude, and not as informative
  234.     as the graphics program.
  235.  
  236.  
  237.     X. Program Output: the Data files
  238.  
  239.     A series of files called 'spdata.x', where 'x' is the integration
  240.     count, is produced as the integrations proceed.  These files are
  241.     used by the graphics program.
  242.  
  243.     The first value in each file is the number of mass points.  Each mass
  244.     point has the following values:
  245.  
  246.       1. Current mass
  247.       2. Pressure
  248.       3. Temperature
  249.       4. Luminosity
  250.       5. Radius
  251.       6. Density
  252.       7. Opacity (-1 if in a convective region)
  253.       8. Energy generation rate
  254.  
  255.  
  256.    XI. Graphical Display in AmigaBasic
  257.  
  258.     This allocates the arrays based on the number of mass points.  As it
  259.     it loading the arrays, it keeps track of high/low values for each
  260.     attribute.  These high/low values are used later to scale the display,
  261.     and are shown on the screen when the arrays are loaded.
  262.  
  263.     There are two kinds of displays: pictures and graphs.  A 'picture' is a
  264.     disk with color shadings used to represent the gradient from low to
  265.     high for the requested data value.  A single large picture, or multiple
  266.     small pictures may be drawn.  A 'graph' is a plot of the data value
  267.     against either mass or radius. Plotting by mass shows the fitting
  268.     point discrepancy, while plotting by radius gives a feel for the
  269.     physical structure.  Any or all data values may be plotted on a single
  270.     graph. 
  271.  
  272.     Note:  plots using the logarithm of the data values do not yet work.
  273.  
  274.  
  275.   XII.    Acknowledgements
  276.  
  277.     Thanks to Bill Evans for his help with the IBM compatability.
  278.  
  279.     Some of the ideas for the display in spdraw.bas were borrowed from
  280.     DeluxDraw.bas by Rick Wirch.    
  281.  
  282.     
  283.